package com.surekam.mnai.service;

import java.util.List;

import com.surekam.mnai.entity.LoadPattern;
import com.surekam.mnai.model.Address;

/**
 * 对数据地址信息的服务类
 * 这个接口的现实类在操作出现异常的时候，返回null,否则返回成功后的对象【添加方法除外，当出现像添加已有数据时【抛出异常】。构成数据链的模式
 * @author caoxu
 */
public interface IAddressService {

	/**
	 * 添加一个数据地址信息 数据不要包含数据id字段的值，设置也会无效
	 * 
	 * @param address
	 *            要添加的数据
	 * @return 返回添加成功后的数据
	 * @throws ServiceException
	 *             添加失败！eg.添加已有数据
	 */
	public Address addAddress(Address address) throws ServiceException;

	/**
	 * 删除一个数据对象
	 * 
	 * @param address
	 *            要删除的数据对像
	 * @return 返回删除的数据对象 (不包含数据id值)，失败返回null
	 */
	public Address delAddress(Address address);

	/**
	 * 更新一个地址数据对象
	 * 
	 * @param address
	 *            要更新的数据
	 * @return 成功为更新后的数据对象，否则null
	 */
	public Address updateAddress(Address address);

	/**
	 * 根据id返回一个地址对象模型
	 * 
	 * @param id
	 *            要选择的数据id
	 * @return 成功返回该地址对象，否则null
	 */
	public Address loadById(String id);

	/**
	 * 根据选择模式返回一个数据集
	 * 假如出现条件错误 返回所有数据集
	 * @param term
	 *            根据选择模式要查询的条件
	 * @param pattern
	 *            查询的模式
	 * 
	 * @return 返回查询到的结果集
	 */
	public List<Address> loadsByPattern(String term, LoadPattern pattern);

	/**
	 * 根据指定的省份与城市返回匹配的单个Address对象。
	 * 
	 * @param province
	 *            省份名称
	 * @param city
	 *            城市名称
	 * @return 如果存在匹配的Address，返回该对象，否则返回null。
	 */
	public Address loadByProvinceAndCity(String province, String city);
}
